…nges

BUG-003/004/010 introduced three breaking changes (data array shape,
fetchedAt rename) without updating the schemaVersion signal. Consumers
that pin on schemaVersion to detect compatibility would silently parse
the wrong shape. Bump to 1.2 and update all hardcoded test assertions,
docs/schema-versioning.md version history, and CHANGELOG.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…type guard

P1: when --json + parent command without subcommand, Commander fires
helpDisplayed with err.message="(outputHelp)". Now uses
resolveTargetCommand to emit "cache: a subcommand is required.
Available: list, clear, ..." instead of the opaque placeholder.

P2: setBrightness/setColor/setColorTemperature in 'devices expand' now
validate device type via findCatalogEntry before building the parameter.
Unsupported types (Bot, Plug, etc.) get a UsageError instead of sending
an invalid request to the API.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…guard)

Also fixes root cause gap: Commander throws 'commander.help' (not
'commander.helpDisplayed') for parent-command-without-subcommand. The
previous P1 fix only covered 'commander.helpDisplayed'; this commit
extends both src/index.ts and tests/helpers/cli.ts to also handle
'commander.help' with the useful subcommand-list message.

New tests (9):
- error-envelope: parent cmd without subcommand exits 2 + useful JSON
- error-envelope: parent cmd with --help exits 0 + structured help JSON
- expand: setBrightness/setColor/setColorTemperature on Color Bulb (happy path)
- expand: setBrightness on unsupported type (Bot) -> UsageError
- expand: setColor on unsupported type (Curtain) -> UsageError
- expand: setBrightness on uncached device -> UsageError
- expand: lighting command in --json mode emits valid envelope

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…d → error envelope

Issue 1: Floor Lamp, Light Strip, Dimmer, Fill Light are supported by
param-validator but absent from the catalog. The catalog check added in
the previous commit wrongly rejected them. Fix: export
isLightingCommandSupported() and use it as fallback when findCatalogEntry
returns null.

Issue 2: rules run --json with automation.enabled=false emitted a
{data:...} success envelope with exit 1, violating the JSON protocol.
Fix: use exitWithError({code:1, kind:'runtime',...}) so the output is
{error:...} consistent with all other failure paths.

New tests (+3): Floor Lamp setBrightness passes, Light Strip setColor
passes, rules run --json disabled emits error envelope with code 1.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…0.2, test count

- json-contract.md: bump schemaVersion examples 1.1 → 1.2 (4 places)
- policy-reference.md: schema file v0.1.json → v0.2.json; v0.2 is now
  the current required version (not opt-in); update schema version
  table, automation block description, exit code table, JSON envelope
  example, common errors table, and "Migrating" section
- README.md: test count 2204 → 2216; add setBrightness/setColor/
  setColorTemperature to `devices expand` examples; correct --json
  error envelope (stdout, not stderr; includes schemaVersion)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Cuts without losing substance:
- ToC: 38-item nested list → compact inline links
- Filter expressions per-command reference → removed (duplicates --help)
- Parameter formats table + prose → condensed to one paragraph
- Project layout tree (85 lines) → one-sentence directory summary
- Rules engine workflow (10 steps + guardrails block) → flat command list
- status-sync required/optional I/O lists → single prose sentence
- mqtt-tail sinks table → mention + pointer to --help
- upgrade-check JSON output dump → single inline note
- Events tail/mqtt-tail pm2/nohup block → removed
- Cache section: two sub-sections + status-cache GC → single table
- Various verbose prose → condensed per-section

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Fix 1 — catalog wins; validator is fallback only (expand.ts + param-validator.ts):
- isColorDevice(): remove Ceiling Light / Ceiling Light Pro — catalog
  marks these "(no RGB)", no setColor command. isBrightnessDevice()
  correctly keeps them (setBrightness and setColorTemperature are listed).
- expand.ts: replace OR check with catalog-first branch. If the device
  is in the catalog, the catalog is authoritative and the heuristic is
  never consulted. The heuristic only runs when findCatalogEntry returns
  null (uncatalogued types like Floor Lamp, Light Strip, Dimmer, Fill Light).

Fix 2 — resolveTargetCommand skips option-value tokens (help-json.ts):
- When walking argv to find the deepest matching subcommand, value-
  consuming flags (--config, --profile, --timeout …) were not handled.
  The value token didn't start with '-', so the walk aborted early and
  the error message pointed at the root command instead of the actual target.
- Fixed by reading Commander's Option.required / .optional metadata to
  detect value-consuming flags and skipping their next token.

Tests: add Ceiling Light regression cases to expand.test.ts; add
value-consuming-flag cases to help-json.test.ts (existing describe block).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- validateParameter: gate setColorTemperature with isBrightnessDevice
  (not isColorDevice) so Ceiling Light gets Kelvin-range validation
- resolveTargetCommand: also search root options after descending into a
  subcommand, so interleaved global flags are consumed correctly
- expand setAll: require Air Conditioner device type before dispatching
- expand setPosition: whitelist Curtain/Roller Shade/Blind Tilt instead
  of treating every non-Blind device as a Curtain
- index.ts: treat explicit `help` subcommand as successful help (exit 0)
- emitStreamHeader: accept optional schemaVersion override; event streams
  now pass EVENTS_SCHEMA_VERSION so header matches record version
- rules.ts: keep automation.enabled=false as code 1 (runtime), not code 2
  (usage) — this is a post-load config state, not bad CLI syntax

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

setColor error no longer lists Ceiling Light as supported, since it
only supports setBrightness and setColorTemperature.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Roller Shade setPosition takes a single 0-100 integer, not the
three-value index,mode,position format used by Curtain. Also corrects
help text that listed Ceiling Light under setColor (no RGB support).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- README: test count 2216→2225, add 4 MCP tools, expand doctor checks to 19
- agent-guide: tool count 21→24, add rule_notifications/rules_explain/rules_simulate
- audit-log: AUDIT_VERSION 1→2, expand kind field to all 10 types
- json-contract: distinguish stream header schemaVersion per command type
- schema-versioning: fix version reference v3.4.1→v3.4.0
- roadmap: mark v0.1 policy as removed in v3.0, drop stale queue item
- policy-reference: fix exit codes, deviceId pattern, add conditions (all/any/not/llm),
  button.pressed event, notify actions, audit/llm_budget config, mark cron/webhook active
- phase4-rules: document notify action type
- mcp.ts help text: twenty-one→twenty-four, add 2 missing tools

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>